📘 Documentation du module xcraft-core-cryo

Le module xcraft-core-cryo est une couche de persistance sophistiquée pour l'écosystème Xcraft, basée sur SQLite. Il implémente un système d'event sourcing qui permet de sauvegarder, récupérer et gérer l'historique des mutations d'état des acteurs Goblin et Elf. Ce module est fondamental pour la persistance des données dans les applications Xcraft, offrant des fonctionnalités avancées comme la recherche plein texte et vectorielle.

• Cryo : Classe principale qui encapsule les fonctionnalités de persistance et de récupération
• SoulSweeper : Utilitaire pour nettoyer les anciennes actions et optimiser la base de données
• StreamSQL : Classes pour la lecture/écriture de flux de données SQL
• Endpoints : Extensions pour connecter Cryo à d'autres systèmes (comme Google Queue)
• SQLite-Vec : Support pour la recherche vectorielle via une extension SQLite

Le module expose une API complète pour la gestion des actions, avec des fonctionnalités de:

• Persistance (freeze)
• Récupération (thaw)
• Synchronisation et transactions
• Recherche plein texte (FTS) et vectorielle (VEC)
• Nettoyage et optimisation des données

Cryo fonctionne selon le principe d'event sourcing :

1. Les actions (événements) sont "gelées" (freeze) dans la base de données SQLite
2. Chaque action contient les informations nécessaires pour reconstruire l'état d'un acteur
3. Les actions peuvent être "dégelées" (thaw) pour reconstruire l'état à un moment précis
4. Le système maintient un historique complet des changements

Les actions sont stockées avec des métadonnées :

• timestamp : Horodatage de l'action
• goblin : Identifiant de l'acteur concerné
• action : Contenu JSON de l'action
• version : Version de l'application
• type : Type d'action (create, persist, etc.)
• commitId : Identifiant de commit pour la synchronisation

Le module offre également des fonctionnalités avancées comme :

• Recherche plein texte via SQLite FTS5
• Recherche vectorielle pour les embeddings (avec dimensions configurables)
• Synchronisation des actions entre différentes instances
• Nettoyage automatique des anciennes actions via SoulSweeper
• Transactions et verrous pour garantir la cohérence des données
• Support pour les worker threads pour le traitement des embeddings

// Dans une méthode d'un acteur Elf
async cryoStuff() {
  const cryo = this.quest.getAPI('cryo');

  // Vérifier si une base de données existe et est vide
  const result = await cryo.isEmpty({
    db: 'myDatabase'
  });
  console.log(result); // {exists: true, empty: false}
}

// Dans une méthode d'un acteur Elf
async freezeSomething() {
  const cryo = this.quest.getAPI('cryo');

  // Geler une action dans la base de données
  await cryo.freeze({
    db: 'myDatabase',
    action: {
      type: 'persist',
      payload: {
        state: {
          id: 'myEntity@1',
          // ... autres propriétés d'état
          meta: {
            status: 'published'
          }
        }
      }
    },
    rules: {
      goblin: 'myEntity-myEntity@1',
      mode: 'last' // Conserver uniquement la dernière action
    }
  });
}

// Dans une méthode d'un acteur Elf
async thawSomething() {
  const cryo = this.quest.getAPI('cryo');

  // Récupérer toutes les actions jusqu'à un timestamp donné
  await cryo.thaw({
    db: 'myDatabase',
    timestamp: '2023-05-01T12:00:00.000Z'
  });

  // Les résultats sont envoyés via des événements
  // resp.events.send('cryo.thawed.myDatabase', rows);
}

// Dans une méthode d'un acteur Elf
async withTransaction() {
  const cryo = this.quest.getAPI('cryo');

  // Démarrer une transaction immédiate
  await cryo.immediate({
    db: 'myDatabase'
  });

  try {
    // Effectuer des opérations dans la transaction
    await cryo.freeze({
      db: 'myDatabase',
      action: {/* ... */},
      rules: {/* ... */}
    });
    
    // Valider la transaction
    await cryo.commit({
      db: 'myDatabase'
    });
  } catch (error) {
    // Annuler la transaction en cas d'erreur
    await cryo.rollback({
      db: 'myDatabase'
    });
  }
}

// Dans une méthode d'un acteur Elf
async cleanupDatabase() {
  const cryo = this.quest.getAPI('cryo');

  // Nettoyer les actions plus anciennes que 30 jours, en gardant 10 actions par acteur
  const changes = await cryo.sweep({
    dbs: ['myDatabase'],
    days: 30,
    max: 10
  });
  console.log(changes); // Nombre d'actions supprimées par base de données
}

• xcraft-core-book : Fournit la classe SQLite utilisée par Cryo
• xcraft-core-utils : Utilisé pour les verrous et autres utilitaires
• xcraft-core-fs : Gestion des fichiers et répertoires
• xcraft-core-transport : Streaming des données
• xcraft-core-etc : Configuration du module
• xcraft-core-goblin : Les acteurs Goblin utilisent Cryo pour persister leur état
• xcraft-core-host : Informations sur l'environnement d'exécution
• @google-cloud/pubsub : Utilisé par l'endpoint GoogleQueue pour la publication de messages

• journal : Mode journal pour SQLite (WAL recommandé pour les performances)
• endpoints : Liste des endpoints à activer (ex: "googleQueue")
• enableFTS : Activer la recherche plein texte
• enableVEC : Activer la recherche vectorielle (nécessite enableFTS)
• fts.list : Liste des bases de données où utiliser FTS (toutes si vide)
• vec.list : Liste des bases de données où utiliser VEC (toutes si vide)
• vec.dimensions : Nombre de dimensions pour les embeddings (défaut: 4096)
• vec.defaultLocale : Locale par défaut pour le partitionnement des vecteurs
• migrations.cleanings : Règles de nettoyage par nom de base de données
• enableTimetable : Activer la table de temps pour des requêtes temporelles avancées
• googleQueue.topic : Topic à utiliser pour publier les messages
• googleQueue.authFile : Fichier d'authentification pour Google Queue
• googleQueue.orderingPrefix : Partie fixe de la clé d'ordonnancement

Classe principale qui implémente toutes les fonctionnalités de Cryo. Elle gère :

• La connexion à SQLite et la définition du schéma de base de données
• Les requêtes SQL pour les différentes opérations (freeze, thaw, etc.)
• Les middlewares pour transformer les données
• Les transactions et verrous pour garantir la cohérence
• Les triggers pour les notifications d'événements
• La gestion des indices et des optimisations

La classe expose de nombreuses méthodes comme freeze, thaw, frozen, restore, etc., qui sont exposées via l'API Xcraft. Elle gère également les migrations de schéma lors des mises à jour.

Utilitaire spécialisé pour nettoyer les anciennes actions et optimiser la base de données :

• sweepByCount : Garde un nombre spécifique d'actions par acteur (entre 1 et 100)
• sweepByDatetime : Supprime les actions antérieures à une date spécifique
• sweepForDays : Stratégie combinée pour garder un historique récent plus détaillé

Le SoulSweeper utilise des requêtes SQL optimisées pour identifier et supprimer les actions obsolètes tout en préservant l'intégrité des données. Il inclut également des fonctionnalités pour analyser et optimiser la base de données après le nettoyage.

Classes pour la lecture/écriture de flux de données SQL :

• ReadableSQL : Stream lisible pour extraire des données de SQLite par lots
• WritableSQL : Stream inscriptible pour insérer des données dans SQLite avec gestion des transactions

Ces classes permettent de traiter efficacement de grandes quantités de données sans surcharger la mémoire, en utilisant le système de streaming de Node.js.

Endpoint pour publier des actions dans Google Cloud Pub/Sub :

• Publie les actions gelées dans un topic Google Cloud
• Ajoute des métadonnées comme l'horodatage et l'identifiant de l'acteur
• Gère l'authentification via un fichier de credentials
• Supporte l'ordonnancement des messages pour garantir leur traitement séquentiel

Chargeur pour l'extension SQLite de recherche vectorielle :

• Détecte la plateforme et l'architecture du système
• Charge l'extension appropriée pour la recherche vectorielle
• Supporte différentes plateformes (Linux, macOS, Windows) et architectures (x86_64, aarch64)
• Gère les erreurs de chargement avec des messages explicites

Worker thread pour le traitement des embeddings vectoriels :

• Exécute les opérations d'embedding dans un thread séparé
• Gère l'insertion et la mise à jour des vecteurs dans la table embeddings
• Utilise la fonction vec_f32 pour convertir les données binaires en vecteurs
• Supporte le partitionnement par locale pour améliorer les performances

Cette documentation a été mise à jour automatiquement.